EuroCD 3/EuroCD 3.iso/Programming/Amos/browser/Manual

Text File | 1998-06-24 | 12KB | 315 lines

                           The Amos Browser
                  Copyright 1995-7 by Steven Goodwin


                            -- Abstract --

This program is a useful tool  for  the Amos, or Amos Pro, programmer.
The browser creates  a  database  of  your  program  that  knows every
variable, procedure and label you've used.  It also knows where it was
used, how often, where the  procedures  were  called from and when the
variables  are  changed.  This  helps  code  management  as  it  shows
redundant  code  and  variables,  where   globals  are  being  changed
(possibly corrupted) and what code  can  be optimised. This program is
intended to work  regardless  of  what  extensions  are  used, and how
complex the code is.

   It extends beyond the usual  facilities  provided by search, as the
browser will differentiate between 'Print', 'Int' and variables called
'RIN', ignore text in quotes  or  segments  of code hiding in comments
and distinguish between local, global  and  shared variables using the
same name! It also know  the  difference between strings, arrays, real
and integer variables!


                          -- Menu Options --

Project:

Open ASCII

   This loads  your  AMOS  program  into  the  browser  and  creates a
database for it. A sample is  included.  The  source input file to the
browser must be:

1. Saved in plain  ASCII  format,  from  within  the  Amos editor. You
should 'select all' and 'save ascii' from within AMOS.

2. Completely open. i.e.  all  closed  procedures  must be opened from
within AMOS using 'Open All'. If  the procedures in question have been
'locked', then simply  delete  the  'Procedure _CLOSED_PROC_NAME' from
the file with a text editor,  and  replace it with a dummy 'Procedure-
End Proc' pair.  This  is  not  essential,  but  it maintains accuracy
within the parser (see Important Information below).

3. A fully legal  program.  i.e.  the  'Test'  (F2) option returns 'No
Errors'. The browser relies on  the  spacing and case-sensitive nature
of  the  source  in  the  Amos  editor.  Changing  it  may  result  in
inaccuracies! If you program using an  external editor you should load
the source into the AMOS editor, and re-save.

   Once loaded, the browser will  scan  your  program, and create its'
own internal tables. This process can  take  a long time. Often two or
three times longer than it does to  'Test' it through AMOS. One reason
is that the source must be scanned  in ASCII mode. AMOS tests it using
a tokenised form, which  is  much  quicked,  due its compacted nature.
(another reason is that Amos scans in assembler...I don't!).


Open Browser

   This loads a '.browse' file into memory, and refreshs each window.

Save Browser

   This saves a '.browse' file  of  the current browse database. Using
this file saves a lot of  time  over  importing an ASCII file, and re-
calculating the database.

Quit

   Leaves the program!


                             -- Window --

Variable Window:

   The left hand side lists  each  variable  used  in the program. The
right hand side shows its definition  and  where it has been used (the
references). The definition list is given thus,

   Definition:
     Variable name (also known as the identifier)
     Variable type (global string, int array, etc)

   References:
     Line XX Procedure it appears in.  Proc_Line
     ..etc..


The 'XX' above consists of two special characters. The first character
is either:

D   Declared - The variables first appearance in the source.
S   Shared   - The variable is declared as shared for this procedure.
               (note, this only appears on one line as all other
               variables of this name within that procedure must, by
               definition, be shared).
-   Nothing special.


The second character is either:

*   The variable is changed on this line. It may be through an
    expression (A=B+4), or an instruction like Inc or Dec. If the
    variable is an array, then changing any element in the array will
    produce a '*'.
:   Nothing special


   The text requester  in  the  centre  of  the  window  allows you to
restrict the variables listed in the list  on the left hand side. This
is done by typing the  variable  name  into the requester and pressing
'Find'. This will then list the  variable  (if it exists), and (on the
right hand side), its definition and references.

   To use wildcards on the variable name,  append  a '*' to the end of
the name. This means  that  'ID_*'  (for  example)  will  list all the
variables that start with 'ID_', and no others. Using '*' or '**' will
list all the variables. A  trailing  wildcard character is, currently,
the only acceptable variation (ie. VAR_*_SIZE will not work).

   The other option in this window  is  a  set of check boxes labelled
'Include?'. These options  specify  what  types  of  variable  will be
included in the search initiated with  the 'Find' button. One point to
bear in mind; if the variable is  a  string array, it will be included
as both a string, AND an array,  so  you will have un-tick each box to
exclude it from the search.

   To list all the variables  in  the  left  hand side scroll box just
press 'Find Variable' with an empty text requester. This does the same
as a search for '*' or '**' (i.e. a search for everything).


Procedure Window:

This functions in the same manner  as  the 'variable window', it shows
each procedure and where it  is  called  from.  The right hand window,
however, has three possible  display  methodologies, selected from the
radio buttons. They are:

References      Shows the procedure name, the line it is declared on,
                and each reference that calls the procedure.

Call Graph      Shows, in a graphical manner, each procedure and what
                subsequent procedures it calls. By starting with the
                main Amos program, it might show:

                        Main Amos Program
                        +--INIT
                        |  +--SETUP_BANKS
                        |  +--LOAD_ICONS
                        +--OPEN_MAIN_WINDOW
                        +--EVENT_LOOP
                        |  +--EMULATE
                        |  +--HANDLE_EVENT
                        |  |  +--HANDLE_MAIN
                        |  |  +--HANDLE_PREFS
                        |  +--NAGWARE_WINDOW
                        +--CLOSE_ALL_WINDOWS
                        +--QUIT

Caller Graph    Much the same as the call graph, this shows the
                "is called by" procedures. So, if your CLEAR_SCREEN
                procedure is being called too often, this graph will
                show you which routines can call it.

                Because it is not possible for a procedure to re-run
                the program (only the Amos editor can do this) the
                list will be empty in this case.

Note: In the current  version,  the  order  of  procedure calls is not
supported, so they may appear in the reverse order of a call graph, or
caller graph list.


Labels Window:

This window works in the same way  as both the variables and procedure
windows. However, this only has 'Find  Label' function. Again, the '*'
wildcard may only be placed at the end of the label identifier.


Preferences Window:

This allows you to set the maximum number of variables, procedures and
labels held  internally.  The  browser  must  be  restarted  for these
options  to  take  effect.   This   information   is   stored  in  the
configuration file which is saved  in  s:  and loaded into memory upon
program boot-up.



                        -- IMPORTANT NOTES --

The main processing routine inside  the  browser is the 'parser'. This
reads through the program file  looking  for variables, procedures and
labels (refered to as identifiers).  However,  when coding this, I had
no access to the actual syntax  rules,  or  the tokenised file form of
AMOS. This meant I  had  to  'reverse-engineer'  my  own rules for the
language. Although I have  tested  a  great  deal  of code through the
parser, I may not have  catered  for  certain  'tricks' or cases which
seem 'obvious' to some programmers. In  which case you may get strange
variables appearing in the browse tables...but it should not be fatal.
Furthermore, the  browser  should  work  through  most  (if  not  all)
extensions.

   Here are some of the more 'exotic' uses of the Amos parser that the
browser WILL cope with:

_CLEAR[SCR=Screen]
_$=""
Data NAME$,ADDRESS$,AGE
LAB: PRC_NOT_LAB : PRC_NOT_LAB


In order to improve the parser  speed,  some liberties were taken. The
most obvious of these is the lack of error checking! If the program is
not correct, or it runs out of  space to hold all the identifiers then
it  will  stop,  and  the  program  will  exit  without  warning.  The
registered version includes  a  'safe'  version  that  will  not exit,
should any of the tables become full.


All identifiers are significant to 32 characters.


When loaded, the browser immediately  creates  space for the variable,
procedure and label  tables.  If  it  suceeds,  the  only other memory
required will be for the ASCII  program. Therefore, if the program can
start, there should be no  memory allocation problems during execution
(saving a browser file also  uses  allocated  memory, but it should be
less than that of the ASCII program - which is currently removed after
parsing - so if the  Amiga  managed  to  allocate  memory for that, it
should be able to do so again).



                    -- Known Bugs and Omissions --


Functions (in the form, Def Fn(x)  etc)  are  not handled. The code is
parsed, although if it deals with  any  variables they will not appear
correct in the list.

When running the browser as an  Amos  Pro accessory (only available to
registered users), using key  shortcuts  inside  the browser can cause
the keys to echo within the Amos Pro editor. They will be visible upon
exit. If present, they will appear at the end of your source code.


                         -- The Final Word --

This program is shareware, you can  use  it for 30 days without paying
for it. If, however, you  want  the  source  (enabling  you to run the
browser as an accessory from within Amos Pro!), or you wish to use the
software after this period, then  send  me  £5,  and I'll return you a
disc with all the source, the  latest version, and any other utilities
I've written that haven't been released yet.

Now,

Q. Where do I send my money?
A. Steven Goodwin
   105 St. Johns Road
   Clacton-on-Sea
   Essex CO16 8DB

Q. What do I say?
A. Try printing this off....
   (or copying the relevant bits if you're without a printer)

o/_________________________ CUT HERE ________________________________
O\

Your Name:_______________
Address  :_______________
          _______________
          _______________
          _______________

Hi Mr. Steven Goodwin,

   I would like to register my copy of The AMOS Browser because

a) It's brilliant!  (a very good reason, I might add)
b) I think I'd prefer the 'safe' version, despite the performance hit.
c) I'd like to run it as an accessory!
d) I need access to the  preferences  because  my programs are too big
and powerful!
e) I have a tremendous guilt complex!
f) All of the above                         (circle as appropriate)

   I enclose a cheque/postal order for £5 (which includes P&P) because
I'm a kind hearted  soul  whos  cares  about  the  people  you make my
software.

   Thanks very much,


      Name ________________ (not completely necessary, but ties up the
                             letter nicely)


o/_________________________ CUT HERE ________________________________
O\


That's all folks!!!! See you on the next release...